docs: add OpenAPI specs for auth service public endpoints - #175
Conversation
One spec per endpoint (grouped by path) covering the public OAuth/OIDC surface: authorize, par, token, introspect, revoke, userinfo, logout, jwks, and discovery metadata. Validated with redocly/cli.
🤖 Augment PR SummarySummary: This PR adds standalone OpenAPI 3.1 specifications for the auth service's public OAuth/OIDC surface. Changes:
🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| RedirectUri: | ||
| name: redirect_uri | ||
| in: query | ||
| required: true |
There was a problem hiding this comment.
AuthorizeRequestParser.resolvePushedRequest requires only the outer client_id and then replaces the rest of the payload, so a valid /authorize?client_id=...&request_uri=... request has no redirect_uri. Marking these parameters required makes the documented GET and POST contracts reject the PAR flow this file describes. Other locations where this applies: auth/open-api/authorize.yaml:109, auth/open-api/authorize.yaml:121, auth/open-api/authorize.yaml:132, auth/open-api/authorize.yaml:305.
Severity: medium
Other Locations
auth/open-api/authorize.yaml:109auth/open-api/authorize.yaml:121auth/open-api/authorize.yaml:132auth/open-api/authorize.yaml:305
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| Space-delimited list. `none` must not be combined with any other value. | ||
| schema: | ||
| type: string | ||
| enum: [none, login, consent, select_account] |
There was a problem hiding this comment.
The parser splits prompt on spaces and accepts combinations such as login consent (rejecting only a combination containing none), but this scalar enum makes every such documented space-delimited combination invalid. This causes validators and generated docs to reject valid authorization requests.
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| description: '`client_secret_basic` — `client_id` as the username, `client_secret` as the password.' | ||
| clientSecretPost: | ||
| type: apiKey | ||
| in: cookie |
There was a problem hiding this comment.
extractCredentials reads client_secret_post exclusively from the parsed form; it never reads a client_secret cookie. Declaring this as a cookie apiKey causes OpenAPI tooling to send the secret in a location the endpoint ignores, despite the body schema description. Other locations where this applies: auth/open-api/par.yaml:72, auth/open-api/revoke.yaml:55, auth/open-api/token.yaml:85.
Severity: medium
Other Locations
auth/open-api/par.yaml:72auth/open-api/revoke.yaml:55auth/open-api/token.yaml:85
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| Cache-Control: | ||
| schema: | ||
| type: string | ||
| const: no-store |
There was a problem hiding this comment.
When JWT deserialization fails, IntrospectionController returns the inactive 200 response directly without either cache header. Therefore this response contract promises Cache-Control: no-store and Pragma: no-cache for an ordinary documented outcome that does not actually include them.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| responses: | ||
| '200': | ||
| $ref: '#/components/responses/LogoutPage' | ||
| '303': |
There was a problem hiding this comment.
performLogout delegates to renderLogout, which always produces a 200 HTML signed-out page and embeds the post-logout URI for client-side navigation; it never sets Location or returns 303. The advertised redirect response is therefore unreachable for successful logout requests. Other locations where this applies: auth/open-api/logout.yaml:77.
Severity: medium
Other Locations
auth/open-api/logout.yaml:77
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| Cache-Control: | ||
| schema: | ||
| type: string | ||
| const: no-store |
There was a problem hiding this comment.
The successful path in TokenEndpointController creates Response.json(response.toJson) without adding Cache-Control, while only its error path adds no-store. This contract consequently guarantees a sensitive token response header that clients do not receive.
Severity: high
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
1 participant
Adds OpenAPI 3.1 specifications for the auth service's public OAuth/OIDC endpoints, one spec per endpoint (grouped by path where GET/POST share a route):
authorize.yaml—GET/POST /authorizepar.yaml—POST /partoken.yaml—POST /tokenintrospect.yaml—POST /introspectrevoke.yaml—POST /revokeuserinfo.yaml—GET/POST /userinfologout.yaml—GET/POST /logoutjwks.yaml—GET /.well-known/jwks.jsonmetadata.yaml—GET /.well-known/oauth-authorization-serverand/.well-known/openid-configurationEach spec was derived directly from the corresponding controller, request parser, and error model, and includes request/response schemas, error variants, and security schemes. Validated with
redocly/cli(no errors).These specs are consumed by the
versola-websitedocs site (companion PR), which renders one documentation page per endpoint from them.Pull Request opened by Augment Code | View session